<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
<head>
	<title>Wiring dependencies</title>
  <link rel="stylesheet" type="text/css" href="documentation.css" />
</head>
<body>
<h1>Wiring dependencies</h1>
<h2>The wire package</h2>
<p><strong>Wire</strong> is a simple dependency injection container for PHP5. It&#039;s implemented as a hybrid registry/DI container, which makes it suitable to use for small as well as bigger projects. It&#039;s a sub project of the Konstrukt library, but it can easily be used on its own. The relevant classes are all in the <code>k/wire</code> namespace, and there are no dependencies on the rest of Konstrukt.</p>
<p>So what is a DI container anyway? Shortly put, it&#039;s a class factory. The benefit of using it is, that it can hide away constructor complexity and that it can remove concrete class dependencies. The latter is perhaps most important, when writing unit tests, while the former helps to simplify code and makes refactoring a lot easier. For a more thorough explanation, you should visit <a href="http://www.picocontainer.org/">www.picocontainer.org</a>.</p>
<h2>Motivation for wire</h2>
<p>Most programs has objects, which are somewhat global in nature; The same instance needs to be shared among several components. The simplest way of acquiring this is, to use some sort of global scope. Be it global variables, singletons or other, global scope introduce severe problems into an application and should therefore be avoided; The details of why, is beyond the scope of this text.</p>
<p>As mentioned, Wire is a hybrid registry/dependency injection container. Unlike other DI containers, it&#039;s relatively simple to configure. It also has sane default behaviour, which means that for simple cases, you don&#039;t need any explicit configuration. This addresses (what I perceive as) the main problem with existing solutions, such as <a href="http://www.picophp.com/">PicoPhp</a> and <a href="http://sourceforge.net/projects/phemto/">Phemto</a>.</p>
<h3>Forces of Wire</h3>
<p>The biggest benefits of Wire, compared to other similar packages are as follows:</p>
<ul>
  <li>Works out-of-the-box. Classes without dependencies, can be be created without any explicit registration.</li>
</ul>
<ul>
  <li>Since Wire can simply be used as a registry, it allows you to an ad-hoc strategy. For example, you could begin by using the simpler registry pattern and only move on to DI, when the need arises. This allows the container to grow with your application, rather than being tailored for a specific style.</li>
</ul>
<ul>
  <li>While the default method to wire components, is to use a configurable factory, Wire allows you to register callbacks as factories. This gives ultimate control for those odd cases, which can otherwise be hard to fit in. It also has a default factory, so for classes, which doesn&#039;t have any dependencies, you don&#039;t need to explicitly register a factory.</li>
</ul>
<ul>
  <li>Another difference from existing solutions is, that it doesn&#039;t use interfaces as markers. If you don&#039;t fancy writing interfaces for everything, you can still use Wire. This is important, because interfaces are a relatively new, and somewhat strange, construction in the PHP language.</li>
</ul>
<ul>
  <li>Finally, Wire supports setter injection. The main usage for this, is to overcome recursive dependencies.</li>
</ul>
<h2>Using Wire as a registry</h2>
<p>Using Wire as a registry is straight forward. You instantiate a new instance of k_wire_Registry and can then use the methods set() and get() to store/retrieve instances. This doesn&#039;t really add any functionality, but since k_wire_Container has the same interface as k_wire_Registry, they become interchangeable. This allows you to escalate to use DI, if you later find the need.</p>
<p>The benefit gained, from using a registry is, that complex constructors can be simplified. For example, instead of this:</p>
<pre class="php"><span class="kw2">class</span> Foo
<span class="br0">&#123;</span>
  <span class="kw2">function</span> __construct<span class="br0">&#40;</span><span class="re0">$bar</span>, <span class="re0">$cux</span>, <span class="re0">$zip</span>, <span class="re0">$zap</span><span class="br0">&#41;</span> <span class="br0">&#123;</span>
    <span class="re0">$this</span>-&gt;<span class="me1">bar</span> = <span class="re0">$bar</span>;
    <span class="re0">$this</span>-&gt;<span class="me1">cux</span> = <span class="re0">$cux</span>;
    <span class="re0">$this</span>-&gt;<span class="me1">zip</span> = <span class="re0">$zip</span>;
    <span class="re0">$this</span>-&gt;<span class="me1">zap</span> = <span class="re0">$zap</span>;
  <span class="br0">&#125;</span>
<span class="br0">&#125;</span></pre><p>You could have this:</p>
<pre class="php"><span class="kw2">class</span> Foo
<span class="br0">&#123;</span>
  <span class="kw2">function</span> __construct<span class="br0">&#40;</span><span class="re0">$registry</span><span class="br0">&#41;</span> <span class="br0">&#123;</span>
    <span class="re0">$this</span>-&gt;<span class="me1">bar</span> = <span class="re0">$registry</span>-&gt;<span class="me1">get</span><span class="br0">&#40;</span><span class="st0">'bar'</span><span class="br0">&#41;</span>;
    <span class="re0">$this</span>-&gt;<span class="me1">cux</span> = <span class="re0">$registry</span>-&gt;<span class="me1">get</span><span class="br0">&#40;</span><span class="st0">'cux'</span><span class="br0">&#41;</span>;
    <span class="re0">$this</span>-&gt;<span class="me1">zip</span> = <span class="re0">$registry</span>-&gt;<span class="me1">get</span><span class="br0">&#40;</span><span class="st0">'zip'</span><span class="br0">&#41;</span>;
    <span class="re0">$this</span>-&gt;<span class="me1">zap</span> = <span class="re0">$registry</span>-&gt;<span class="me1">get</span><span class="br0">&#40;</span><span class="st0">'zap'</span><span class="br0">&#41;</span>;
  <span class="br0">&#125;</span>
<span class="br0">&#125;</span></pre><p>If you later decide to add a dependency to that class, the signature of the constructor wouldn&#039;t change. This makes it easier to add new dependencies and remove them again.</p>
<p>The biggest downside of using a registry is, that it isn&#039;t apparent from the interface alone, which dependencies a given class has. For example, one couldn&#039;t know that Foo has four dependencies in the above example, without looking at the implementation of the constructor.</p>
<p>Another problem is, that all <em>potential</em> dependencies must be created in advance. So if you don&#039;t know for sure, if Foo is going to be instantiated, you still need to load all its dependencies into the registry. This is problematic in PHP, since each process is very short-lived.</p>
<div class="note">Note: A registry should <em>never</em> be made globally available. Any code, which needs access to it, should get it passed in.</div>
<h2>Upgrading the registry with a factory</h2>
<p>To fix the issue of creating dependencies in advanced, you can use factories to create the dependencies on demand. Wire supports this -- Instead of using k_wire_Registry, you can use k_wire_Container. The container works as the registry, but allows you to register a factory for creating dependencies. There are two kinds of factories; Callbacks and configurable factories. Callbacks are the more primitive of the two, so we&#039;ll cover those first.</p>
<p>Let&#039;s assume that your application has a database connection object, which looks a bit like this:</p>
<pre class="php"><span class="kw2">class</span> DatabaseConnection
<span class="br0">&#123;</span>
  <span class="kw2">function</span> __construct<span class="br0">&#40;</span><span class="re0">$host</span>, <span class="re0">$username</span>, <span class="re0">$password</span><span class="br0">&#41;</span> <span class="br0">&#123;</span>
    <span class="co1">// ...</span>
  <span class="br0">&#125;</span>
<span class="br0">&#125;</span></pre><p>Presumably, we may or may not need an instance. Since it&#039;s rather costly to create a connection, if it&#039;s never used, we set up a factory for creating it:</p>
<pre class="php"><span class="re0">$container</span> = <span class="kw2">new</span> k_wire_Container<span class="br0">&#40;</span><span class="br0">&#41;</span>;
<span class="re0">$container</span>-&gt;<span class="me1">registerConstructor</span><span class="br0">&#40;</span>
  <span class="st0">&quot;DatabaseConnection&quot;</span>,
  <span class="kw3">create_function</span><span class="br0">&#40;</span>
    <span class="st0">'$className, $args, $registry'</span>,
    <span class="st0">'return new $className(&quot;localhost&quot;, &quot;root&quot;, &quot;secret&quot;);'</span>
  <span class="br0">&#41;</span>
<span class="br0">&#41;</span>;</pre><p>It&#039;s now possible to ask the container for an instance of <em>DatabaseConnection</em>. The first time, it will be created, from the registered factory. Any subsequent calls will return the first instance.</p>
<pre class="php"><span class="re0">$connection</span> = <span class="re0">$container</span>-&gt;<span class="me1">get</span><span class="br0">&#40;</span><span class="st0">'DatabaseConnection'</span><span class="br0">&#41;</span>;
<span class="kw3">assert</span><span class="br0">&#40;</span><span class="re0">$connection</span> instanceOf DatabaseConnection<span class="br0">&#41;</span>; <span class="co1">// yields true</span>
<span class="re0">$connection2</span> = <span class="re0">$container</span>-&gt;<span class="me1">get</span><span class="br0">&#40;</span><span class="st0">'DatabaseConnection'</span><span class="br0">&#41;</span>;
<span class="kw3">assert</span><span class="br0">&#40;</span><span class="re0">$connection</span> === <span class="re0">$connection2</span><span class="br0">&#41;</span>; <span class="co1">// yields true</span></pre><p>The argument for <code>registerConstructor</code> is a <a href="http://docs.php.net/callback">callback</a>. You can use anything, which is a valid callback.</p>
<h2>Configurable factories</h2>
<p>While callback factories are flexible, they are also a bit awkward. The recommended way to create factories, is therefore with the configurable factory. The following shows the same example as above, using a configurable factory:</p>
<pre class="php"><span class="re0">$container</span> = <span class="kw2">new</span> k_wire_Container<span class="br0">&#40;</span><span class="br0">&#41;</span>;
<span class="re0">$factory</span> = <span class="re0">$container</span>-&gt;<span class="me1">register</span><span class="br0">&#40;</span><span class="st0">'DatabaseConnection'</span><span class="br0">&#41;</span>;
<span class="re0">$factory</span>-&gt;<span class="me1">registerConstructor</span><span class="br0">&#40;</span><span class="kw2">new</span> k_wire_ConstantDependency<span class="br0">&#40;</span><span class="st0">'localhost'</span><span class="br0">&#41;</span><span class="br0">&#41;</span>;
<span class="re0">$factory</span>-&gt;<span class="me1">registerConstructor</span><span class="br0">&#40;</span><span class="kw2">new</span> k_wire_ConstantDependency<span class="br0">&#40;</span><span class="st0">'root'</span><span class="br0">&#41;</span><span class="br0">&#41;</span>;
<span class="re0">$factory</span>-&gt;<span class="me1">registerConstructor</span><span class="br0">&#40;</span><span class="kw2">new</span> k_wire_ConstantDependency<span class="br0">&#40;</span><span class="st0">'secret'</span><span class="br0">&#41;</span><span class="br0">&#41;</span>;</pre><h2>Shared dependencies</h2>
<p>Most dependencies are shared throughout the application. For example, you would probably want to use the same DatabaseConnection instance for all dependants. When you register a dependency as a <em>shared dependency</em>, there will only be one instance per container. For example:</p>
<pre class="php"><span class="re0">$factory</span> = <span class="re0">$container</span>-&gt;<span class="me1">register</span><span class="br0">&#40;</span><span class="st0">'Foo'</span><span class="br0">&#41;</span>;
<span class="re0">$factory</span>-&gt;<span class="me1">registerConstructor</span><span class="br0">&#40;</span><span class="kw2">new</span> k_wire_SharedDependency<span class="br0">&#40;</span><span class="st0">'bar'</span><span class="br0">&#41;</span><span class="br0">&#41;</span>;
<span class="re0">$factory</span> = <span class="re0">$container</span>-&gt;<span class="me1">register</span><span class="br0">&#40;</span><span class="st0">'Cux'</span><span class="br0">&#41;</span>;
<span class="re0">$factory</span>-&gt;<span class="me1">registerConstructor</span><span class="br0">&#40;</span><span class="kw2">new</span> k_wire_SharedDependency<span class="br0">&#40;</span><span class="st0">'bar'</span><span class="br0">&#41;</span><span class="br0">&#41;</span>;</pre><p>In the above example, <em>Foo</em> and <em>Cux</em> will be created with the same instance of <em>Bar.</em></p>
<h2>Default factory</h2>
<p>To make things easier, it&#039;s not necessary to register a factory for a class, which has an empty constructor. So in the previous example, one could register <em>Foo</em> as follows:</p>
<pre class="php"><span class="re0">$factory</span> = <span class="re0">$container</span>-&gt;<span class="me1">register</span><span class="br0">&#40;</span><span class="st0">'Foo'</span><span class="br0">&#41;</span>;
<span class="re0">$factory</span>-&gt;<span class="me1">registerConstructor</span><span class="br0">&#40;</span><span class="kw2">new</span> k_wire_SharedDependency<span class="br0">&#40;</span><span class="st0">'bar'</span><span class="br0">&#41;</span><span class="br0">&#41;</span>;
<span class="re0">$factory</span>-&gt;<span class="me1">registerConstructor</span><span class="br0">&#40;</span><span class="kw2">new</span> k_wire_SharedDependency<span class="br0">&#40;</span><span class="st0">'cux'</span><span class="br0">&#41;</span><span class="br0">&#41;</span>;
<span class="re0">$factory</span>-&gt;<span class="me1">registerConstructor</span><span class="br0">&#40;</span><span class="kw2">new</span> k_wire_SharedDependency<span class="br0">&#40;</span><span class="st0">'zip'</span><span class="br0">&#41;</span><span class="br0">&#41;</span>;
<span class="re0">$factory</span>-&gt;<span class="me1">registerConstructor</span><span class="br0">&#40;</span><span class="kw2">new</span> k_wire_SharedDependency<span class="br0">&#40;</span><span class="st0">'zap'</span><span class="br0">&#41;</span><span class="br0">&#41;</span>;</pre><p>That is all, that is needed to be able to create an instance of <em>Foo.</em> Although, if you want, you are free to register each of the dependencies explicitly:</p>
<pre class="php"><span class="re0">$container</span>-&gt;<span class="me1">register</span><span class="br0">&#40;</span><span class="st0">'Bar'</span><span class="br0">&#41;</span>;
<span class="re0">$container</span>-&gt;<span class="me1">register</span><span class="br0">&#40;</span><span class="st0">'Cux'</span><span class="br0">&#41;</span>;
<span class="re0">$container</span>-&gt;<span class="me1">register</span><span class="br0">&#40;</span><span class="st0">'Zip'</span><span class="br0">&#41;</span>;
<span class="re0">$container</span>-&gt;<span class="me1">register</span><span class="br0">&#40;</span><span class="st0">'Zap'</span><span class="br0">&#41;</span>;</pre><h2>Transient dependencies</h2>
<p>So far we&#039;ve covered <em>constant dependencies</em> and <em>shared dependencies</em>. However, sometimes a class may need a fresh instance of a given class, rather than share it with others. This is known as a <em>transient dependency.</em> You can register such a dependency like this:</p>
<pre class="php"><span class="re0">$factory</span> = <span class="re0">$container</span>-&gt;<span class="me1">register</span><span class="br0">&#40;</span><span class="st0">'Foo'</span><span class="br0">&#41;</span>;
<span class="re0">$factory</span>-&gt;<span class="me1">registerConstructor</span><span class="br0">&#40;</span><span class="kw2">new</span> k_wire_TransientDependency<span class="br0">&#40;</span><span class="st0">'bar'</span><span class="br0">&#41;</span><span class="br0">&#41;</span>;
<span class="re0">$factory</span> = <span class="re0">$container</span>-&gt;<span class="me1">register</span><span class="br0">&#40;</span><span class="st0">'Cux'</span><span class="br0">&#41;</span>;
<span class="re0">$factory</span>-&gt;<span class="me1">registerConstructor</span><span class="br0">&#40;</span><span class="kw2">new</span> k_wire_TransientDependency<span class="br0">&#40;</span><span class="st0">'bar'</span><span class="br0">&#41;</span><span class="br0">&#41;</span>;</pre><p>In the above example, <em>Foo</em> and <em>Cux</em> will be created with different instances of <em>Bar.</em></p>
<h2>Userland dependencies</h2>
<p>The main use for a container is to create shared instances. However, you may also use it for creating transient instances. Rather than having to write an ad hoc factory, you get the benefit of using the same familiar and tested interface. To create a transient instance (Eg. a new one for each time), you can call the method <code>create()</code> on  the container.</p>
<p>Transient instances often require one or more unique dependencies, in addition to other dependencies. For example, a Article class, representing an article in a CMS, might need the article ID. You can create a factory, which requires userland arguments. These factories can only be called by invoking <code>create()</code>. Assume the mentioned Article object looks like this:</p>
<pre class="php"><span class="kw2">class</span> Article
<span class="br0">&#123;</span>
  <span class="kw2">function</span> __construct<span class="br0">&#40;</span><span class="re0">$databaseConnection</span>, <span class="re0">$articleId</span><span class="br0">&#41;</span> <span class="br0">&#123;</span>
    <span class="co1">// ...</span>
  <span class="br0">&#125;</span>
<span class="br0">&#125;</span></pre><p>It can be registered as follows:</p>
<pre class="php"><span class="re0">$factory</span> = <span class="re0">$container</span>-&gt;<span class="me1">register</span><span class="br0">&#40;</span><span class="st0">'Foo'</span><span class="br0">&#41;</span>;
<span class="re0">$factory</span>-&gt;<span class="me1">registerConstructor</span><span class="br0">&#40;</span><span class="kw2">new</span> k_wire_SharedDependency<span class="br0">&#40;</span><span class="st0">'DatabaseConnection'</span><span class="br0">&#41;</span><span class="br0">&#41;</span>;
<span class="re0">$factory</span>-&gt;<span class="me1">registerConstructor</span><span class="br0">&#40;</span><span class="kw2">new</span> k_wire_UserDependency<span class="br0">&#40;</span><span class="br0">&#41;</span><span class="br0">&#41;</span>;</pre><p>And used:</p>
<pre class="php"><span class="re0">$article42</span> = <span class="re0">$container</span>-&gt;<span class="me1">create</span><span class="br0">&#40;</span><span class="st0">'Article'</span>, <span class="nu0">42</span><span class="br0">&#41;</span>;</pre><h2>Setter injection</h2>
<p>While not something you are likely to need a lot, there can be times, where you need a recursive dependency. Eg. class A depends on B and B depends on A. Obviously, you can&#039;t pass the dependencies in the constructor, since that would require both instances to be created before the other.<br />
As a golden rule, recursive dependencies should be avoided; They are a sign of unnecesary complexity. However, if you need it for some reason, you can use late dependencies. This works by creating the instances, and the assign the dependencies afterwards.</p>
<p>There are two variations of late dependencies; Setter injection and property injection. The former works by calling a setter-method, while the latter sets a property directly. To access the property directly, it must be declared public, and because of this, setter injection is usually the better choice of the two.</p>
</body>
</html>